home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / bricons.z / bricons / slib / X11 / bricons.txt < prev    next >
Text File  |  1994-09-26  |  11KB  |  397 lines
  1.  
  2.  
  3.  
  4. BRICONS(l)        MISC. REFERENCE MANUAL PAGES         BRICONS(l)
  5.  
  6.  
  7.  
  8. NAME
  9.      bricons - quick start  up  utility  for  applications  using
  10.      text, icons, colour icons and pop-up menus on an X display
  11.  
  12. SYNOPSIS
  13.      bricons  [options]
  14.      [-file] [-col] [-help]
  15.      [-bw] [-bh] [-bmdir] [-default]
  16.  
  17. DESCRIPTION
  18.      Bricons program allows the user to quickly start up applica-
  19.      tions  by  selecting the appropriate button from the display
  20.      and pressing the left mouse button.  A maximum of up to six-
  21.      teen main menu buttons can be displayed. Each main menu but-
  22.      ton can launch an application or pop-up a sub menu  contain-
  23.      ing  more  buttons. The buttons can be represented as a bit-
  24.      map, text or a colour icon (i.e Pixmap).
  25.  
  26.      Information on how the program is  to  present  each  button
  27.      (either  as  a bitmap, text or colour icon) and the applica-
  28.      tion that is to be executed if that button  is  selected  is
  29.      contained  in  script  file  called  .briconsrc.   This file
  30.      should be stored in the same directory  as  the  program  is
  31.      executed from.
  32.  
  33.      The .briconsrc file contains a number of key words which are
  34.      used to indicate if the button label is some text, bitmap or
  35.      pixmap and if the button is to pop-up a sub menu or launch a
  36.      program.  These key words are explained below:
  37.  
  38.      The .briconsrc file should start with the keyword  %icon  or
  39.      %text  or %pixmap The key word %icon indicates that the but-
  40.      ton label is a bitmap.  This should be followed by the  file
  41.      name containing the bitmap.  For example:
  42.  
  43.                            %icon clock.icon
  44.  
  45.      The key word %pixmap indicates that the button  label  is  a
  46.      colour  pixmap.   This  should  be followed by the full path
  47.      name where the pixmap can be found.  For example:
  48.  
  49.                   %pixmap /usr/cur/bri/xpm/clock.xpm
  50.  
  51.      The key word %text indicates that the button label  is  some
  52.      text.   The  text can be split over three lines by using the
  53.      new line character \n.  For example:
  54.  
  55.                       %text Line1\nLine2\nLine3
  56.  
  57.      would be presented as:
  58.                                 Line1
  59.                                 Line2
  60.  
  61.  
  62.  
  63. Sun Release 4.1  Last change: 16th November 1992                1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. BRICONS(l)        MISC. REFERENCE MANUAL PAGES         BRICONS(l)
  71.  
  72.  
  73.  
  74.                                 Line3
  75.  
  76.      Once a  button  has  been  selected  it  is  prevented  from
  77.      accidentally  being  re-selected by "graying out" the button
  78.      (default action).  Sometimes however it maybe  desirable  to
  79.      allow the button to be selected more than once.  This can be
  80.      done be using the keyword %icon+ or %pixmap+ or %text+
  81.  
  82.      The next line in the .briconsrc file should  either  contain
  83.      the key word %sub_menu or the application to be started.  If
  84.      the name of an application  is given then a check is made to
  85.      see if such an program can be executed.  If the program does
  86.      not exist or is not in the users path then an error  message
  87.      is printed and the button associated with the application is
  88.      ignored.
  89.  
  90.      If the key word %sub_menu is used then a pop-up sub menu  is
  91.      created.   Any further buttons defined in the briconsrc file
  92.      will appear in the sub menu for that button  until  the  key
  93.      word  %end_sub_menu  is found.  A maximum of ten buttons are
  94.      allowed in a single pop-up sub menu.
  95.  
  96.      Any line in the .briconsrc file starting with a #  character
  97.      is treated as a comment and will be ignored.
  98.  
  99.      This program has four default buttons labelled source, edit,
  100.      help  and  quit.   The  edit  button allows the user to edit
  101.      there icon file (default being an  empty  ./briconsrc  file)
  102.      and  to  add  or  delete  buttons from the script file.  The
  103.      source button causes the program to distory all the  current
  104.      buttons  being  displayed  and  re-read  the  icon  file and
  105.      display the new buttons.
  106.  
  107. OPTIONS
  108.      bricons accepts all of  the  standard  X   Toolkit   command
  109.      line options along with the additional options listed below:
  110.  
  111.      -file
  112.           Tells the program to read  this  file  instead  of  the
  113.           default file.
  114.  
  115.      -col Indicates the number of  buttons  in  a  column  before
  116.           starting  a  new row.  The default number of columns is
  117.           15.
  118.  
  119.      -help
  120.           Tells the program the path for the help file.
  121.  
  122.      -bmdir
  123.           This program will search the default  bitmap  directory
  124.           (./bitmaps)  for  any  bitmaps  that  are to be used to
  125.           represent buttons.  If you wish to add different bitmap
  126.  
  127.  
  128.  
  129. Sun Release 4.1  Last change: 16th November 1992                2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. BRICONS(l)        MISC. REFERENCE MANUAL PAGES         BRICONS(l)
  137.  
  138.  
  139.  
  140.           directories  then  use  this command line argument fol-
  141.           lowed by a colon separated list  of  path  names.   For
  142.           example  if  the  program  needs to find bitmaps in two
  143.           different directories then the following can be entered
  144.           at the command line:
  145.  
  146.            bricons -bmdir /usr/local/bitmaps:/usr/mydir/bitmaps
  147.  
  148.      -default
  149.           Toggle used for  including/not  including  the  default
  150.           Edit  Icons   button in the bricons program.  This flag
  151.           expects a Boolean value.  If  the  bricons  program  is
  152.           called  with  the  -default  flag set to False then the
  153.           Edit Icons  button is not included.
  154.  
  155.      -bw  Specify the width of each button.
  156.  
  157.      -bh  Specify the height of each button.
  158.  
  159.  
  160. X DEFAULTS
  161.      The bricons program reads the .Xdefaults file  and  Xbricons
  162.      resource  file  during  startup  and  uses  the  appropriate
  163.      resource  specification  to  customise  the  appearance   or
  164.      characteristics  of  its  display.  This program understands
  165.      all of the core resource names and classes as well as:
  166.  
  167.      no_of_cols
  168.           Specifies the number of buttons in a column.
  169.  
  170.      icon_file
  171.           Specifies path name for icon file to be read.
  172.  
  173.      help_file
  174.           Specifies path name for help file.
  175.  
  176.      icon_dirs
  177.           Specifies path name for bitmap directories.
  178.  
  179.      button_w
  180.           Specify the width of each button.
  181.  
  182.      button_h
  183.           Specifies the height of each button.
  184.  
  185. SETTING BITMAP DIRECTORIES
  186.      This section explains how to specify bitmap file paths using
  187.      the  .Xdefaults  file.  For the quickest and simplest method
  188.      see the OPTIONS section under -bmdir.
  189.  
  190.      This program will search the default  bitmap  directory  for
  191.      any bitmaps that are to be used to represent buttons. If the
  192.  
  193.  
  194.  
  195. Sun Release 4.1  Last change: 16th November 1992                3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. BRICONS(l)        MISC. REFERENCE MANUAL PAGES         BRICONS(l)
  203.  
  204.  
  205.  
  206.      user wishes the program to search other directories for bit-
  207.      map  files  then  this  should  be  specified  in  the users
  208.      .X11defaults file.  *BitmapFilePath: should  be  added  fol-
  209.      lowed  by  colon separated path names where the bitmap files
  210.      can be found.  For example:
  211.  
  212.      *BitmapFilePath:    /usr/local/include/X11/bitmaps:/usr/mydir/bitmaps
  213.  
  214. FORMAT OF PIXMAP FILES
  215.      This program uses version 3.2 of the xpm  libraries  written
  216.      by  Arnaud  Le Hors (source code can be found from anonymous
  217.      ftp to export.lcs.mit.edu and from many other  sites).   The
  218.      bricons program will produce colour bitmap buttons from pix-
  219.      map files provided that these files are in the correct  for-
  220.      mat.   Below  is  a outline summary of the format for pixmap
  221.      files.  For more detailed information please consult the xpm
  222.      manual.   These  files  are text files so they can be edited
  223.      using a normal text editor.
  224.  
  225.      The XPM format presents a C syntax, in order to provide  the
  226.      ability  to  include XPM files in C.  It is in fact an array
  227.      of strings composed of six different sections as follows:
  228.  
  229.      /* XPM */
  230.      static char * <variable name> [] = {
  231.      /* width height ncolours chars_per_pixel */
  232.      <values>
  233.      /* colours */
  234.      <colours>
  235.      /* pixels */
  236.      <Pixels>
  237.      <Extensions>
  238.      };
  239.  
  240.  
  241.      For example:
  242.  
  243.      /* XPM */
  244.      static char * clock [] = {
  245.      /* width height ncolors chars_per_pixel */
  246.      "125 85 4 1",
  247.      /* colours */
  248.      "       c #ffffffffffff",
  249.      "B      c #ffff00000000",
  250.      "C      c #ffffffff0000",
  251.      "D      c #000000000000",
  252.      "    BBBBBBBB  BBBB BBBB    BBBB  BBBBBBB",
  253.      "    BB BB BB   BB   BBB    BBB    BB    B",
  254.      "    B  BB  B   BB   BBB    BBB    BB    B",
  255.      cont.....
  256.      "                                         "};
  257.  
  258.  
  259.  
  260.  
  261. Sun Release 4.1  Last change: 16th November 1992                4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. BRICONS(l)        MISC. REFERENCE MANUAL PAGES         BRICONS(l)
  269.  
  270.  
  271.  
  272. RESOURCE FILES
  273.      The Xbricons file specifies the required resources.  To make
  274.      sure  the  program uses the resources file set the following
  275.      line in your .login:
  276.             setenv  XUSERFILESEARCHPATH ~/app_defaults/%N
  277.  
  278.      and place all all resources in the app_defaults directory.
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Sun Release 4.1  Last change: 16th November 1992                5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. BRICONS(l)        MISC. REFERENCE MANUAL PAGES         BRICONS(l)
  335.  
  336.  
  337.  
  338. WIDGETS
  339.      The bricons program is  a  toolkit-based  application  which
  340.      consists  of  a combination of widgets.  In order to specify
  341.      resources, it is useful to know the hierarchy of the widgets
  342.      which compose bricons.  In the list below, indentation indi-
  343.      cates hierarchical structure.   The  widget  class  name  is
  344.      given first, followed by the widget instance name.
  345.  
  346.           Xbricons  toplevel
  347.                Form box
  348.                     Command   action[18]
  349.                     OverrideShell  popup_shell
  350.                          Form popup_layout
  351.                          Command   sub_action[10]
  352.  
  353. EXAMPLE
  354.      Below is an example of a simple .briconsrc file:
  355.  
  356.      # <-- a line starting with a '#' is a comment line
  357.      #
  358.      #       Bri's icon file
  359.      #
  360.  
  361.      # first line must have keyword %icon or %text
  362.      # to indicate if button is an icon
  363.  
  364.      %icon calculator
  365.      xcalc
  366.      %text Games\n sub\n menu
  367.      %sub_menu
  368.           %text xeyes
  369.           xeyes
  370.           %text othello
  371.           othello
  372.      %end_sub_menu
  373.  
  374.  
  375.  
  376. BUGS
  377.      After selecting the source button the  buttons  may  not  be
  378.      re-displayed  correctly.   Selecting  the  source  button  a
  379.      second time may help.
  380.  
  381. AUTHOR
  382.      Bruce R Ingram, University of Kent at Canterbury.
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393. Sun Release 4.1  Last change: 16th November 1992                6
  394.  
  395.  
  396.  
  397.